Identity Provider Configuration

Configuring a Identity Provider

To configure an application as a PicketLink Identity Provider you need to follow this steps:

Configure the web.xml.
Configure an Authenticator.
Configure a Security Domain for your application.
Configure PicketLink JBoss Module as a dependency.
Create and configure a file named WEB-INF/picketlink.xml.

Configuring the web.xml

Before configuring your application as an Identity Provider you need to add some configurations to your web.xml.

Let's start by defining a security-constraint element to restrict access to resources from unauthenticated users:

<security-constraint> 
    <web-resource-collection> 
        <web-resource-name>Manager command</web-resource-name> 
        <url-pattern>/*</url-pattern> 
    </web-resource-collection> 
    <auth-constraint> 
        <role-name>manager</role-name> 
    </auth-constraint> 
</security-constraint>


<security-role>
    <description>
      The role that is required to log in to IDP Application
    </description>
    <role-name>manager</role-name>
</security-role>

As you can see above, we define that only users with a role named manager are allowed to access the protected resources. Make sure to give your users the same role you defined here, otherwise they will get a 403 HTTP status code.

The next step is define your FORM login configuration using the login-config element:

<login-config>
    <auth-method>FORM</auth-method>
    <realm-name>PicketLink IDP Application</realm-name>
    <form-login-config> 
        <form-login-page>/jsp/login.jsp</form-login-page> 
        <form-error-page>/jsp/login-error.jsp</form-error-page> 
    </form-login-config> 
</login-config>

Make sure you have inside your application the pages defined in the elements form-login-page and form-error-page.

Please, make sure you have a welcome file page in your application. You can define it in your web.xml or simply create an index.jsp at the root directory of your application.

The picketlink.xml configuration file

All the configuration for an especific Identity Provider goes at the WEB-INF/picketlink.xml file. This file is responsible to define the behaviour of the Authenticator. During the identity provider startup, the authenticator parses this file and configures itself.

Bellow is how the picketlink.xml file should looks like:

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">


    <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1">

        <IdentityURL>http://localhost:8080/idp/ </IdentityURL>


        <Trust>
            <Domains>locahost,mycompany.com</Domains>
        </Trust>

        <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">

            <Auth Key="KeyStoreURL" Value="/jbid_test_keystore.jks" />
            <Auth Key="KeyStorePass" Value="store123" />
            <Auth Key="SigningKeyPass" Value="test123" />
            <Auth Key="SigningKeyAlias" Value="servercert" />

            <ValidatingAlias Key="localhost" Value="servercert" />
            <ValidatingAlias Key="127.0.0.1" Value="servercert" />

        </KeyProvider>

    </PicketLinkIDP>

    <PicketLinkSTS xmlns="urn:picketlink:identity-federation:config:1.0" TokenTimeout="1000" ClockSkew="1000">
        <TokenProviders>
            <TokenProvider ProviderClass="org.picketlink.identity.federation.core.saml.v2.providers.SAML20AssertionTokenProvider"
                TokenType="urn:oasis:names:tc:SAML:2.0:assertion" TokenElement="Assertion"
                TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion" />
        </TokenProviders>
    </PicketLinkSTS>

    <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">

        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />

     </Handlers>

</PicketLink>

The schema for the picketlink.xml file is available here: https://github.com/picketlink/picketlink/blob/master/modules/federation/src/main/resources/schema/config/picketlink_v2.1.xsd.

PicketLinkIDP Element

This element defines the basic configuration for the identity provider. The table bellow provides more information about the attributes supported by this element:

Name	Description	Value
AssertionValidity	Defines the timeout for the SAML assertion validity, in miliseconds.	Defaults to *300000. Deprecated. Use the PicketLinkSTS element, instead.*
RoleGenerator	Defines the name of the org.picketlink.identity.federation.core.interfaces.RoleGenerator subclass to be used to obtain user roles.	Defaults to org.picketlink.identity.federation.core.impl.EmptyRoleGenerator.
AttributeManager	Defines the name of the org.picketlink.identity.federation.core.interfaces.AttributeManager subclass to be used to obtain the SAML assertion attributes.	Defautls to org.picketlink.identity.federation.core.impl.EmptyAttributeManager.
StrictPostBinding	SAML Web Browser SSO Profile has a requirement that the IDP does not respond back in Redirect Binding. Set this to false if you want to force the IDP to respond to SPs using the Redirect Binding.	Values: true\|false. Defaults to true, the IDP always respond via POST Binding.
SupportsSignatures	Indicates if digital signature/verification of SAML assertions are enabled. If this attribute is marked to true the Service Providers must support signatures too, otherwise the SAML messages will be considered as invalid.	Values: true\|false. Defaults to false.
Encrypt	Indicates if SAML Assertions should be encrypted. If this attribute is marked to true the Service Providers must support signatures too, otherwise the SAML messages will be considered as invalid.	Values: true\|false. Defaults to false
IdentityParticipantStack	Defines the name of the org.picketlink.identity.federation.web.core.IdentityParticipantStack subclass to be used to register and deregister participants in the identity federation.	Defaults to org.picketlink.identity.federation.web.core.IdentityServer.STACK.
HostedURI	Defines an URI used to redirect users after an IDP-initiated authentication or if you access the IDP root directly with an authenticated user.	Default to /hosted/.
SSLClientAuthentication	Indicates if the IDP should authenticate clients when using SSL based on their certificates.	Values true\|false. Defaults to false.

IdentityURL Element

This element value refers to the URL of the Identity Provider.

Eg.: http://localhost:8080/idp/

Trust/Domains Elements

The Trust and Domains elements defines the hosts trusted by this Identity Provider. You just need to inform a list of comma separated domain names.

SAML Digital Signature Configuration (KeyProvider Element)

To enable digital signatures for the SAML assertions you need to configure:

Set the SupportsSignature attribute to true;
Add the SAML2SignatureGenerationHandler and the SAML2SignatureValidationHandler in the handlers chain (Handler Element).
Configure a KeyProvider* *element.

SAML Encryption Configuration

To enable encryption for SAML assertions you need to configure:

Set the Encrypt attribute to true;
Add the SAML2EncryptionHandler and the SAML2SignatureValidationHandler in the handlers chain (Handler Element).
Configure a KeyProvider* *element.

SAML Handlers Configuration (Handlers Element)

PicketLink provides some built-in Handlers to help the Identity Provider Authenticator processing the SAML requests and responses.

The handlers are configured through the Handlers element.

SecurityToken Service Configuration (PicketLinkSTS Element)

When configuring the IDP, you do not need to specify the PicketLinkSTS element in the configuration. If it is ommited PicketLink will load the default configurations from a file named core-sts inside the picketlink-core-VERSION.jar.

Override this configuration only if you need to. Eg.: change the token timeout or specify a custom Security Token Provider for SAML assertions.

See the documentation at Security Token Service Configuration.